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1.  OBJECTIVES 

The  principal  goal  of  this  project  was  to  make  specific  enhancements  to  the  seismic  analysis 
program,  "geotool",  and  generate  program  documentation,  "geotool"  is  an  X  Windows- 
based  graphics  tool  for  displaying  wave  forms  and  performing  b^ic  analysis  operations  in 
a  highly  interactive  and  flexible  environment.  The  enhancements  included  in  this  project 
were  aimed  at  increasing  the  program's  versatility  in  a  research  environment  where  user 
analysis  needs  are  diverse,  while  at  the  same  time  providing  a  common  platform  of  data  I/O 
and  graphics  functionality. 

This  report  consists  of  a  brief  introduction  followed  by  several  sections  describing  the 
enhancements  made  to  the  program.  A  user's  manual  is  provided  separately  entitled 
"geotool  Sourcebook".  This  latter  document  as  well  as  the  program  itself  is  available  by 
anonymous  ftp  from  the  Center  for  Monitoring  Research.  They  can  be  found  in  the 
directory  /pub/coyne/geotool  as  compressed  "tar"  files. 


2.  INTRODUCTION 

"geotool"  was  originally  developed  for  ARPA/NMRO  under  the  Nuclear  Monitoring 
Research  and  Development  (NMRD)  initiative  to  construct  a  "Research  Testbed"  at  the 
Center  for  Seismic  Studies  (CSS),  and  it  is  now  widely  used  in  both  the  nuclear  monitoring 
and  general  seismic  research  communities.  Portability  was  a  key  design  goal  to  enable  the 
program  to  be  used  in  a  variety  of  computing  environments.  An  X  window  server  and  a 
UNIX  operating  system  are  the  basic  requirements.  Initially  developed  on  SUN 
computers,  the  software  has  since  been  ported  to  a  number  of  UNIX  platforms,  including 
HP,  IBM,  Linux  and  SGI. 

"geotool"  can  interface  with  specialized  software  such  as  the  ISIS  interprocess 
communication  system  and  an  ORACLE  database  server,  which  allows  it  to  be  integrated 
within  the  Intelligent  Monitoring  System  (IMS)  at  the  Center  for  Monitoring  Research,  but 
versions  of  the  program  which  do  not  depend  on  ISIS  and  ORACLE  are  available.  The 
primary  data  format  is  CSS-3.0,  which  can  be  read  directly  from  disk  files  or  from  a 
relational  database. 

The  following  sections  describe  the  enhancements  that  were  made  to  the  program  as  part  of 
this  project. 


3.  MODULARITY 

Several  aspects  of  "geotool"  were  modularized  to  improve  its  maintainability  and  dso 
provide  for  easy  methods  of  extending  the  functionality  of  the  program.  The  user  interface 
of  "geotool"  is  completely  defined  by  X  resources  using  the  Widget  Creation  Library 
[Smith  and  Nye,  1992].  This  separates  the  interface  from  the  C  code,  and  allows  the  entire 
interface  to  be  customized  on  a  local  or  per-user  basis.  As  explained  in  Chapter  6  of  the 
"geotool  Sourcebook",  a  naming  convention  was  adopted  for  all  interface  elements  or 
widgets,  such  as  buttons,  text  fields  or  plotting  windows,  which  makes  it  possible  to 
identify  widgets  by  looking  only  at  the  interface  and  not  the  C  code.  Through  X  resources, 
the  attributes  of  any  widget,  such  as  size,  position,  font,  color,  text,  etc.,  can  be  accessed 
and  modified. 
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The  C  code  in  "geotool"  was  divided  into  three  major  parts:  the  I/O  routines,  the  analysis 
functions  and  the  core  part  of  "geotool".  The  VO  routines  and  the  analysis  functions  are 
decoupled  from  the  core  of  "geotool"  and  communicate  with  the  "geotool"  core  via  an 
Application  Programmer’s  Interface.  Consequently,  these  parts  of  "geotool"  can  be 
extended  without  modifying  the  core  part  of  "geotool"  by  using  shared  library  technology. 

The  core  part  of  "geotool"  manages  the  data  after  it  has  been  read  ^d  provides  graphic 
services  via  the  widget  set  developed  for  "geotool”.  Some  data  attributes  are  stored  in  a^ 
local  X  resource  database  maintained  by  "geotool".  The  seismic  data  stored  in  geotool  are 
organized  in  three  autonomous  lists  of  wave  forms,  arrivals  and  origins.  This  is  an 
improvement  that  greatly  increases  the  flexibility  for  handling  data. 


4.  SHARED  LIBRARIES 

Shared  library  technology  has  been  exploited  as  a  mechanism  for  adding  functionality  to 
"geotool"  without  requiring  the  core  part  of  the  program  to  be  modified  or  even  recompiled. 
The  I/O  routine  interfaces  have  been  standardized,  which  allows  the  easy  addition  of  new 
data  formats.  There  is  a  suite  of  prototype  I/O  routines  with  standardized  arguments.  For 
example,  the  basic  "geotool"  reads  three  different  formats:  CSS-2.8/3.0,  SAC  and  ASCII. 
Each  of  these  formats  has  a  routine  for  reading  wave  form  data;  cssReadData,  sacReadData 
and  asciiReadData.  The  argument  list,  or  input  and  output  to  the  ReadData  prototype 
routine  is  defined  to  be  format  independent. 

Similarly,  there  are  other  prototype  VO  routines,  such  as  ReadArrival,  AddAmval, 
ReadOrigin,  etc.,  and  the  corresponding  format  specific  routines  cssRead/^val,  __ 
sacReadArrival,  asciiReadArrival,  etc.  A  new  data  format  can  be  added  to  "geotool' 
through  the  use  of  X  resources  and  shared  Ubraries,  without  requiring  any  ch^ges  to  the 
code  or  even  recompiling  the  code.  For  example,  to  add  a  new  data  format  called  bmary 
to  the  program,  the  formatList  resource  would  be  set  as  "geotool.formatList: 
css,sac,ascii,binary".  A  shared  library,  mylib.so.l,  containing  binary  versions  of  Ae 
prototype  I/O  routines  would  be  created  and  identified  to  "geotool"  at  run  time  with  a 
resource  line  "geotool.binary.sharedLib:  mylib.so.r'.  "geotool"  d;^amically  links  to  the 
"binary"  I/O  routines,  whose  names  are  identified  with  resources  like 
"geotool.binary.readDataCallback:  binaryReadData". 

"geotool"  automatically  determines  the  format  of  a  data  file  by  attempting  to  read  with  ^ch 
format’s  ReadData  routine.  It  is  not  necessary  to  have  a  complete  suite  of  I/O  routines  for 
each  format.  For  example,  if  there  were  no  binary  Add  Arrival  routine  identified,  then  the 
add-arrival  function  in  "geotool"  would  give  a  warning  for  binary  data,  but  other  functtons 
would  behave  normally. 

Shared  library  technology  has  also  been  utilized  to  isolate  "geotooF’s  analysis  functions 
from  the  data  I/O  and  graphics  parts  of  "geotool".  It  is  now  straight  forward  to  add 
additional  analysis  functions  to  the  program,  and  this  can  be  done  on  a  user  basis,  without 
changing  the  core  "geotool"  C-code  or  recompiling.  Additional  windows  can  be  added  to 
the  interface  for  controlling  these  new  analysis  tools.  New  windows  containing  plotting 
widgets,  text  fields  and  interface  buttons  can  be  described  by  X  resources.  At  mn  time 
"geotool"  reads  a  file  of  such  resources  and  the  new  windows  are  created  and  tied  to  new 
analysis  functions  in  a  user  defined  shared  library  by  the  Widget  Creation  Library  routines 
in  the  core  part  of  "geotool". 
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5.  CSS  TABLES 


■Many  more  of  the  CSS-3.0  schema  tables  (Anderson  et  al.,  1990)  ^  now  supported  by 
"geotool".  "geotool"  reads  each  table  from  a  flat  file  whose  suffix  is  the  table  name.  When 
wave  form  data  is  read  via  a  file  containing  wfdisc  records,  the  working  dirwtory  is 
automatically  searched  for  other  CSS  table-files  which  are  linked  to  the  wfdisc  file  by  a 
common  prefix.  For  example,  if  a  file  named  "example.wfdisc"  is  read,  the  following 
table-files  will  be  read,  if  they  are  found: 

•  example.affiliation 

•  example.arrival 

•  example.assoc 

•  example.instrument 

•  example.lastid 

•  example,  origerr 

•  example.origin 

•  example.sensor 

•  example.site 

•  example.sitehan 

•  example.stassoc 

•  example.wftag 

In  addition,  a  user  can  point  "geotool"  to  a  directory  of  "global"  table-files,  that  will  be  read 
and  used  throughout  the  session  for  all  wfdisc-files  input. 

New  text  interfaces  have  been  added  to  "geotool"  for  displaying  the  attributes  of  these 
tables.  These  interfaces  arc  very  flexible,  allowing  the  user  to  interactively  adjust  Ae  subset 
of  attributes  displayed,  their  order  and  format  Many  attributes  can  also  be  edited  in  these 
interfaces  and  the  changes  will  be  recorded  in  the  corresponding  files. 


6.  SCHEME 

A  scheme  language  interpreter  has  been  added  to  "geotool".  The  primary  design  goal  for  its 
addition  was  to  facilitate  automated  processing.  The  goal  was  not  to  add  functionality 
accessible  only  from  scheme,  but  to  provide  a  mechanism  to  drive  what  already  exits.  The 
rational  for  this  design  was  to  automate  "geotool"  to  do  mundane  tasks  while  limiting 
scheme's  prevalence,  since  most  users  are,  at  best,  unfamiliar  with  the  language. 

This  optional  scheme  interface  is  described  in  Chapter  7  of  the  "geotool  Sourcebook". 
Basically  it  allows  a  user  to  automate  any  sequence  of  interactive  commands  that  he  would 
want  to  repeat  often. 
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7.  OTHER  ENHANCEMENTS 

There  are  many  other  miscellaneous  enhancements  that  have  been  made  to  geotool  and 
some  of  them  are  simply  listed  below. 

•  Several  enhancements  were  made  to  the  wave  form  display  widget  (the  main 
window).  More  time  scale  options  were  added,  such  as  variable,  hours-minutes- 
seconds  ^d  epochal  time.  The  graphics  for  moving  and  overlaying  wave  forms  was 
improved,  eUminating  an  irritating  flicker  from  the  previous  version.  Amplitude 
scales  were  added  to  the  wave  forms.  Automatic  non-overlapping  wave  form 
positioning  is  now  an  option. 

•  The  File  Listing  window,  in  which  wave  form  records  are  selected  for  input,  has 
been  enhanced  by  the  addition  of  more  constraints  that  can  be  used  to  specify  a 
record  subset. 

•  The  Filter  window  now  offers  a  list  of  predefined  filter  settings.  A  tapering 
option  was  added  to  the  filter  function. 

•  The  FK  plot  identifies  the  point  of  maximum  amplitude,  and  a  Beam  option  was 
added  to  the  FK  menu  that  creates  a  beamed  wave  form  for  the  azimuth  and 
slowness  corresponding  to  the  maximum  fk  amplitude. 

•  Many  options  were  added  to  the  FT  window:  smoothing;  display  modes  including 
median,  percentiles,  mean  and  standard  deviation;  amplitude  or  power,  displacement, 
velocity  or  acceleration,  dB  relative  to  nanometers.  CSS-3.0  instrument  response 
files  are  automatically  input  in  order  to  display  spectra  in  nanometers. 

•  The  Map  window  was  enhanced  by  changing  to  a  higher  resolution  coastline 
vector  database  and  adding  political  boundaries.  Origin  error  eUipses  are  now  plotted 
and  azimuth  arcs  are  automatically  tied  to  the  Rotation  and  FK  options.  A  simple 
mechanism  for  plotting  user  defined  overlays  on  the  map  was  added. 

•  "geotool"  can  serve  as  a  wave  form  viewer  when  connected  to  World  Wide  Web 
browsers. 


8.  SUMMARY 

The  enhancements  described  in  this  report,  along  with  the  documentation  increase  Ae 
effectiveness  and  versatility  the  seismic  analysis  program  "geotool".  The  program  is 
already  widely  used  in  the  ARPA  seismological  research  community.  A  users  manual  is 
available  in  Postscript  format  which  can  be  downloaded  along  with  the  software  package 
itself  by  anonymous  ftp  from  the  Center  for  Monitoring  Research.  This  manual  includes  a 
tutorial  for  first-time  users  and  installation  notes  for  the  package.  Comments  on  the  package 
may  be  directed  to  the  Principal  Investigators,  ihenson@seismo.css.gov  and 
coyne  @  seismo.css.gov. 
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